Node / meshtastic / Meshtastic-Android / files / .github / agents / speckit.optimize.tokens.agent.md

Displaying Raw • View rendered • Download

---

description: Track and report token usage across extensions and governance files.

handoffs:

Tff7b72- label: Optimize governance

agent: speckit.optimize.run

prompt: Run a full governance audit to reduce token overhead

Tff7b72- label: Amend constitution

agent: speckit.constitution

Tc9d1d9 prompt: Apply approved token-reduction changes to the constitution

Tc9d1d9---

<!-- Extension: optimize -->

<!-- Config: .specify/extensions/optimize/ -->

Tc9d1d9## User Input

Ta5d6ff```Ta5d6fftext

$ARGUMENTS

Ta5d6ff```

You **MUST** consider the user input before proceeding (if not empty).

Arguments: Ta5d6ff`--diff` to compare against the previous report, Ta5d6ff`--extensions-only` to skip governance files.

Tc9d1d9## Goal

Measure the token footprint of every governance document and extension command that AI agents load during sessions. Produce a token usage report with per-file costs, per-extension rankings, session load estimates, and historical trends. Suggest optimizations but apply **nothing** without user consent.

This command answers: "How much of my AI context window is consumed by governance and tooling overhead before any actual work begins?"

Tc9d1d9## Operating Constraints

Tff7b72- **Suggest-only**: NEVER modify any file without explicit user consent. This command is read-only by default.

Tff7b72- **Spec-kit standard paths**: Start from Ta5d6ff`.specify/` as the source of truth. Discover tool-specific files (Ta5d6ff`CLAUDE.md`, Ta5d6ff`AGENTS.md`, Ta5d6ff`.github/copilot-instructions.md`) by checking if they exist.

Tff7b72- **Reproducible estimates**: Token estimation uses chars ÷ Ta5d6ff`chars_per_token` (default: 4.0, configurable). Note this is approximate — actual tokenizer counts vary by model. Lower ratios (3.0–3.5) give more conservative estimates for code-heavy files.

Tc9d1d9## Execution Steps

Tc9d1d9### 1. Discover Governance Files

Scan for all files that AI agents may load on session start or command invocation:

**Always-loaded files** (loaded on every AI session):

Tff7b72- Ta5d6ff`CLAUDE.md` (if present — Claude Code sessions)

Tff7b72- Ta5d6ff`AGENTS.md` (if present — generic agent sessions)

Tff7b72- Ta5d6ff`.github/copilot-instructions.md` (if present — Copilot sessions)

**Constitution chain**:

Tff7b72- Ta5d6ff`.specify/memory/constitution.md` — read to check if it is a redirect or contains content

Tff7b72- If redirect, follow to the actual file (e.g., Ta5d6ff`.ai/rules/constitution.md`)

Tff7b72- Record both the pointer and the target

**Supplementary governance files**:

Tff7b72- Glob Ta5d6ff`.ai/rules/*.md` (if directory exists)

Tff7b72- Glob Ta5d6ff`.specify/memory/*.md` (beyond constitution)

Tff7b72- Any other files referenced from the always-loaded files (parse for markdown links and "Read and follow" patterns)

For each file: record path, exists (bool), size in bytes, size in characters, estimated tokens (chars ÷ Ta5d6ff`chars_per_token`).

Tc9d1d9### 2. Inventory Extension Commands

For each extension listed in Ta5d6ff`.specify/extensions.yml` → Ta5d6ff`installed:`:

Tff7b721. Read Ta5d6ff`.specify/extensions/<ext-id>/extension.yml`

Tff7b722. For each command in Ta5d6ff`provides.commands[]`:

Tff7b72- Locate the command file (the Ta5d6ff`file:` field points to the source)

Tff7b72- Measure its character count and estimated tokens

Tff7b723. Sum total tokens per extension

Produce a ranked list of extensions by total token footprint.

Tc9d1d9### 3. Calculate Per-Session Load Estimates

Estimate what gets loaded for different session types:

**Baseline session** (always loaded):

Tff7b72- Sum tokens of always-loaded governance files

Tff7b72- This is the minimum overhead before any work begins

**Constitution-aware session** (baseline + constitution):

Tff7b72- Add constitution chain tokens

Tff7b72- Add supplementary governance file tokens

**Command invocation** (per command):

Tff7b72- For each extension command, the cost is: baseline + command file tokens + any files the command references (parse "Read" / "Load" instructions in the command file)

Present estimates for each context window size in Ta5d6ff`context_window_sizes` config (default: 8K, 32K, 128K, 200K, 1M).

Ta5d6ff```Ta5d6ffmarkdown

Tc9d1d9### Per-Session Token Budget

| Session Type | Tokens | % of 8K | % of 32K | % of 128K | % of 200K | % of 1M |

|---|---|---|---|---|---|---|

| Baseline (governance only) | X | X% | X% | X% | X% | X% |

| + Constitution | X | X% | X% | X% | X% | X% |

| + Largest command | X | X% | X% | X% | X% | X% |

Ta5d6ff```

Tc9d1d9### 4. Historical Trend Analysis

Check for a previous report at Ta5d6ff`.specify/optimize/token-report.md`.

If found:

Tff7b72- Parse the previous report's per-file token counts

Tff7b72- Compare each file: current vs previous

Tff7b72- Calculate per-file growth/reduction

Tff7b72- Flag files growing faster than Ta5d6ff`file_growth_percent` threshold (default: 20%)

Tff7b72- Show overall governance token trend (growing / stable / shrinking)

If not found:

Tff7b72- Note this is the first run — no trend data available

Tff7b72- Recommend running periodically to track trends

Tc9d1d9### 5. Generate Token Usage Report

Present the full report to the user:

Ta5d6ff```Ta5d6ffmarkdown

Tc9d1d9## Token Usage Report

**Date**: <ISO date>

**Target Context Window**: <from config> tokens

Tc9d1d9### Governance Files

| File | Exists | Chars | Est. Tokens | Load Timing | Notes |

|---|---|---|---|---|---|

| CLAUDE.md | Yes/No | X | X | Always | — |

| .specify/memory/constitution.md | Yes/No | X | X | Always | Redirect to <path> |

| <actual constitution path> | Yes | X | X | Always | Actual content |

| AGENTS.md | Yes/No | X | X | Always | — |

| .github/copilot-instructions.md | Yes/No | X | X | Always | — |

| .ai/rules/<file>.md | Yes | X | X | On reference | — |

**Total governance tokens**: X (~Y% of <context_window>)

Tc9d1d9### Extension Commands (ranked by token cost)

| Extension | Commands | Total Tokens | Largest Command | Largest Tokens |

|---|---|---|---|---|

| <ext-id> | X | X | <cmd> | X |

| ... | ... | ... | ... | ... |

**Total extension tokens**: X (loaded per invocation, not per session)

Tc9d1d9### Per-Session Estimates

[Table from Step 3]

Tc9d1d9### Historical Trend

| File | Previous | Current | Change | Growth % | Flag |

|---|---|---|---|---|---|

| <path> | X | X | +/-X | X% | [!] if > threshold |

**Overall governance trend**: Growing / Stable / Shrinking (X% change)

Tc9d1d9### Optimization Suggestions

[Ranked by projected token savings — suggest only, do not apply]

Tff7b721. **<suggestion>**: <description> — saves ~X tokens

Tff7b722. ...

Ta5d6ff```

Tc9d1d9### 6. Save Report

Ask the user: "Save this report to Ta5d6ff`.specify/optimize/token-report.md` for trend tracking?"

If approved:

Tff7b72- Write the report to Ta5d6ff`.specify/optimize/token-report.md` (create directory if needed)

Tff7b72- This enables historical trend comparison on future runs

If declined:

Tff7b72- Report is displayed in conversation only, not persisted

Tc9d1d9### 7. Suggest Next Steps

Based on findings:

Ta5d6ff```Ta5d6ffmarkdown

Tc9d1d9### Recommended Actions

Tff7b72- If governance budget exceeds threshold → suggest Ta5d6ff`/speckit.optimize.run` for full audit

Tff7b72- If specific extensions are oversized → suggest reviewing those command files for compression

Tff7b72- If CLAUDE.md duplicates constitution → suggest consolidation

Tff7b72- If growth trend is upward → suggest scheduling periodic token audits

Ta5d6ff```

Tc9d1d9## Operating Principles

Tc9d1d9### Read-Only Default

This command reads and measures — it does not modify. The only write action is saving the report file, and only with explicit consent.

Tc9d1d9### Consistent Estimation

Token counts use chars ÷ Ta5d6ff`chars_per_token` (configurable, default: 4.0) throughout. This is an approximation — actual counts vary by tokenizer. Use 3.0–3.5 for code-heavy projects, 4.0 for prose-heavy. The approximation is consistent across runs, making trend analysis valid even if absolute numbers are approximate.

Tc9d1d9### Actionable Output

Every metric in the report is paired with a concrete action: "X tokens in version history → remove via Ta5d6ff`/speckit.optimize.run`". Raw numbers without actions are noise.

Tc9d1d9### Trend Over Snapshots

A single run provides a snapshot. Repeated runs provide a trend. The historical comparison is the most valuable output — it tells you whether your governance is growing, stable, or shrinking over time.